'****************************************************************************
'********************             HANDY.BAS              ********************
'********************            Version 1.0             ********************
'********************                by                  ********************
'********************         Raymond W. Marron          ********************
'********************      HOMONCULOUS PROGRAMMING       ********************
'********************             Mesa, AZ               ********************
'****************************************************************************

INTRODUCTION:

     HANDY.BAS is a collection of procedures for use in QBASIC and QuickBasic
programs.  It is applicable to both beginning and advanced BASIC programmers,
both of whom will appreciate the heavily documented code.

     All the procedures were designed to be as modular as possible. This
means that they won't unexpectedly alter anything in your program unless
specifically asked to do so.

     There is more where this came from!  I am putting together a libarary
of more complicated procedures that includes light-bar menus, screensavers,
and other powerful stuff.  If you're interested, just E-mail me.  Also, if
you have a programming problem that you just can't figure out, I like to 
solve problems (anything except graphics).  I can be contacted on CompuServe 
at 74220,2344.

     HANDY.BAS and its associated files are to be distributed freely, and you 
may use any part of them in your programs with no obligation to the author.  
IMPORTANT:  Please distribute only the original, unmodified ZIP file.

     The files that should have appeared upon unzipping HANDY.ZIP are:

     HANDY.TXT      This file!
     HANDY.BAS      The source code (ASCII text)
     HANDY.QLB      QuickBasic Quick Library
     HANDY.LIB      QuickBasic Library
     HANDY.OBJ      The library object file
     NEW_PROG.BAS   A template for organizing the main module of your code.
     QUICKREF.TXT   A page of really handy information you will want to print
                    out and tape to your computer desk.
     KEYPRESS.BAS   How do I know when the user presses Shift-F1?  Just run
                    this program to get the ASCII value of almost any key
                    combination.


CREDITS/DISCLAIMER:     

     All the source code is completely original.  However, I would like to      
credit the authors of CA-Clipper and the Grumpfish library for Clipper with
the ideas for some of the procedures, namely Center() and the various Pad() 
functions.  Also, I would like to thank all the freeware and shareware
programmers out there that have inspired me to create and share.

     I can not guarantee that this software is completely bug-free.  If you
find any, please notify me immediately.  I am not responsible for anything
that happens to you, your computer or your data as a result of using or 
attempting to use this software.  Bla, bla, bla... Whatever.  It's free.


PREPARATION FOR USE:
                                   QBASIC

     To use the HANDY procedures, simply cut and paste the procedures and
their declarations into your program.  Some procedures are dependent upon
others in the library, and they will need to be included as well.  The source
code of each procedure lists the FUNCTIONs or SUBs that are required for its
operation.  Those enclosed in parentheses support the supporting routines.
This nesting of required procedures should be no more than two calls deep.
                                 
                                 QuickBasic

     HANDY.BAS and its respective .QLB, .LIB, and .OBJ files were created 
with QuickBasic 4.5.  They may work with earlier versions, but this has not
been tested.  To use the library, you can cut and paste as in the QBASIC 
description above, or use the procedures straight out of the Quick Library.
If using the Quick Library, only those routines that are directly called by
your program need to be declared in the main module.


REQUIRED LINES:

     A few specific lines of code are required in the main module of your
program in order to use the HANDY.BAS procedures.  They are:

DEFINT A-Z          HANDY.BAS assumes all variables are integers unless
                    specifically declared otherwise.  If this line does not
                    appear, all variables are assumed to be single-precision.
                    It's not REALLY SUPER important, but it's a good practice
                    because integers use less memory.

CONST TRUE = -1     These constants are used throughout HANDY.BAS.  Besides,
CONST FALSE = NOT   they are very descriptive and make your programs very 
             TRUE   easy to read.

RANDOMIZE TIMER     This seeds the random number generator.  Without this
                    line, your program will generate the SAME random numbers
                    each time it is run.  Specifically, it is required by
                    Dice() and CrazyName$().  The only reason to omit this 
                    line would be for testing. 

DIM SHARED ecode    The global variable ecode and it's assiociated error   
MiscErr:            handler, "MiscErr", are required by a number of functions
     ecode = ERR    in HANDY.BAS, mostly in the file and disk functions.  I
     RESUME NEXT    find that a simple error handler like this works for most
                    of my error trapping needs.


If you use NEW_PROG.BAS as a template for your new programs, these lines are
already included for you!

The functions themselves are not described in this text file.  Their 
descriptions and usage are all included in the source code, at the beginning
of each procedure.  I find it's easier to have the reference right there in
the source code than in a separate document.

ENJOY!

Ray Marron
HOMONCULOUS PROGRAMMING

*** End of File ***